Crate vello

Vello is an experimental 2d graphics rendering engine written in Rust, using wgpu. It efficiently draws large 2d scenes with interactive or near-interactive performance.

Motivation

Vello is meant to fill the same place in the graphics stack as other vector graphics renderers like Skia, Cairo, and its predecessor project Piet. On a basic level, that means it provides tools to render shapes, images, gradients, texts, etc, using a PostScript-inspired API, the same that powers SVG files and the browser <canvas> element.

Vello’s selling point is that it gets better performance than other renderers by better leveraging the GPU. In traditional PostScript-style renderers, some steps of the render process like sorting and clipping either need to be handled in the CPU or done through the use of intermediary textures. Vello avoids this by using prefix-scan algorithms to parallelize work that usually needs to happen in sequence, so that work can be offloaded to the GPU with minimal use of temporary buffers.

This means that Vello needs a GPU with support for compute shaders to run.

Getting started

Vello is meant to be integrated deep in UI render stacks. While drawing in a Vello scene is easy, actually rendering that scene to a surface setting up a wgpu context, which is a non-trivial task.

To use Vello as the renderer for your PDF reader / GUI toolkit / etc, your code will have to look roughly like this:

// Initialize wgpu and get handles
let (width, height) = ...;
let device: wgpu::Device = ...;
let queue: wgpu::Queue = ...;
let surface: wgpu::Surface<'_> = ...;
let texture_format: wgpu::TextureFormat = ...;
let mut renderer = Renderer::new(
   &device,
   RendererOptions {
      surface_format: Some(texture_format),
      use_cpu: false,
      antialiasing_support: vello::AaSupport::all(),
      num_init_threads: NonZeroUsize::new(1),
   },
).expect("Failed to create renderer");

// Create scene and draw stuff in it
let mut scene = vello::Scene::new();
scene.fill(
   vello::peniko::Fill::NonZero,
   vello::Affine::IDENTITY,
   vello::Color::rgb8(242, 140, 168),
   None,
   &vello::Circle::new((420.0, 200.0), 120.0),
);

// Draw more stuff
scene.push_layer(...);
scene.fill(...);
scene.stroke(...);
scene.pop_layer(...);

// Render to your window/buffer/etc.
let surface_texture = surface.get_current_texture()
   .expect("failed to get surface texture");
renderer
   .render_to_surface(
      &device,
      &queue,
      &scene,
      &surface_texture,
      &vello::RenderParams {
         base_color: Color::BLACK, // Background color
         width,
         height,
         antialiasing_method: AaConfig::Msaa16,
      },
   )
   .expect("Failed to render to surface");
surface_texture.present();

See the examples/ folder to see how that code integrates with frameworks like winit and bevy.

Re-exports

• pub use util::block_on_wgpu;
• pub use peniko;
• pub use peniko::kurbo;

Modules

• glyph
  Support for glyph rendering.
• util
  Simple helpers for managing wgpu state and surfaces.

Structs

• AaSupport
  Represents the set of antialiasing configurations to enable during pipeline creation.
• BufferProxy
  Proxy used as a handle to a buffer.
• BumpAllocators
  Temporary export, used in with_winit for stats Counters for tracking dynamic allocation on the GPU.
• DrawGlyphs
  Builder for encoding a glyph run.
• FullShaders
• ImageProxy
  Proxy used as a handle to an image.
• Recording
  List of Commands for an engine to execute in order.
• Render
  State for a render in progress.
• RenderParams
  Parameters used in a single render that are configurable by the client.
• Renderer
  Renders a scene into a texture or surface.
• RendererOptions
• ResourceId
• Scene
  The main datatype for rendering graphics.
• ShaderId

Enums

• AaConfig
  Represents the antialiasing method to use during a render pass.
• Command
  Single command inside a Recording to get executed by an engine.
• ImageFormat
• ResourceProxy

Type Aliases

• Error
  Catch-all error type.
• Result
  Specialization of Result for our catch-all error type.